.\" $OpenBSD: X509_print_ex.3,v 1.4 2021/10/29 09:42:07 schwarze Exp $
.\"
.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: October 29 2021 $
.Dt X509_PRINT_EX 3
.Os
.Sh NAME
.Nm X509_print_ex ,
.Nm X509_CERT_AUX_print ,
.Nm X509_print_ex_fp ,
.Nm X509_print ,
.Nm X509_print_fp
.Nd pretty-print an X.509 certificate
.Sh SYNOPSIS
.In openssl/x509.h
.Ft int
.Fo X509_print_ex
.Fa "BIO *bio"
.Fa "X509 *x"
.Fa "unsigned long nameflags"
.Fa "unsigned long skipflags"
.Fc
.Ft int
.Fo X509_CERT_AUX_print
.Fa "BIO *bio"
.Fa "X509_CERT_AUX *aux"
.Fa "int indent"
.Fc
.Ft int
.Fo X509_print_ex_fp
.Fa "FILE *fp"
.Fa "X509 *x"
.Fa "unsigned long nameflags"
.Fa "unsigned long skipflags"
.Fc
.Ft int
.Fo X509_print
.Fa "BIO *bio"
.Fa "X509 *x"
.Fc
.Ft int
.Fo X509_print_fp
.Fa "FILE *fp"
.Fa "X509 *x"
.Fc
.Sh DESCRIPTION
.Fn X509_print_ex
prints information contained in
.Fa x
to
.Fa bio
in human-readable form.
Printing is aborted as soon as any operation fails, with the exception
that failures while attempting to decode or print the public key,
the X.509 version 3 extensions, or non-standard auxiliary data are
not considered as errors.
.Pp
By default, the following blocks of information are printed
in the following order.
Each block can be skipped by setting the corresponding bit in
.Fa skipflags ,
provided in parentheses after each block description.
.Bl -bullet
.It
A pair of lines reading
.Qq Certificate:\&
and
.Qq Data:\&
containing no information.
.Pq Dv X509_FLAG_NO_HEADER
.It
The certificate version number as defined by the standard,
followed in parentheses by the value contained in the version field
in hexadecimal notation.
See
.Xr X509_get_version 3
for details.
.Pq Dv X509_FLAG_NO_VERSION
.It
The serial number of the certificate as returned by
.Xr X509_get_serialNumber 3 .
If it is not \-1 and converting it to
.Vt long
succeeds, it is printed in both decimal and hexadecimal format.
If it is \-1, too wide to fit in
.Vt long ,
or conversion fails, it is printed byte-by-byte in hexadecimal notation.
.Pq Dv X509_FLAG_NO_SERIAL
.It
The name of the signature algorithm is printed with
.Xr X509_signature_print 3 .
.Pq Dv X509_FLAG_NO_SIGNAME
.It
The issuer name returned by
.Xr X509_get_issuer_name 3
is printed with
.Xr X509_NAME_print_ex 3 .
.Pq Dv X509_FLAG_NO_ISSUER
.It
The validity period from
.Xr X509_get_notBefore 3
to
.Xr X509_get_notAfter 3
is printed using
.Xr ASN1_TIME_print 3 .
.Pq Dv X509_FLAG_NO_VALIDITY
.It
The subject name returned from
.Xr X509_get_subject_name 3
is printed with
.Xr X509_NAME_print_ex 3 .
.Pq Dv X509_FLAG_NO_SUBJECT
.It
The public key algorithm is printed with
.Xr i2a_ASN1_OBJECT 3 ,
and the public key returned from
.Xr X509_get_pubkey 3
with
.Xr EVP_PKEY_print_public 3 .
.Pq Dv X509_FLAG_NO_PUBKEY
.It
All X.509 extensions contained in the certificate are printed with
.Xr X509V3_extensions_print 3 .
.Pq Dv X509_FLAG_NO_EXTENSIONS
.It
The signature is printed with
.Xr X509_signature_print 3 .
.Pq Dv X509_FLAG_NO_SIGDUMP
.It
Non-standard auxiliary data associated with the certificate is printed
using the function
.Fn X509_CERT_AUX_print
documented below.
.Pq Dv X509_FLAG_NO_AUX
.El
.Pp
The
.Fa nameflags
argument modifies the format for printing X.501
.Vt Name
objects contained in
.Fa x .
It is passed through to
.Xr X509_NAME_print_ex 3 .
If
.Fa nameflags
is
.Dv X509_FLAG_COMPAT ,
the
.Fa indent
argument of
.Xr X509_NAME_print_ex 3
is set to 16 spaces and the traditional SSLeay format generated by
.Xr X509_NAME_print 3
is used.
Otherwise, if the only bit set in
.Dv XN_FLAG_SEP_MASK
is
.Dv XN_FLAG_SEP_MULTILINE ,
.Fa indent
is set to 12 spaces.
Otherwise,
.Fa indent
is set to zero.
.Pp
.Fn X509_CERT_AUX_print
prints information contained in
.Fa aux
to
.Fa bio
in human-readable form with a left margin of
.Fa indent
spaces.
If
.Fa aux
is
.Dv NULL ,
it prints nothing.
.Pp
Information is printed in the following order:
.Bl -bullet
.It
Purposes the certificate is intended to be used for as set with
.Xr X509_add1_trust_object 3 ,
each printed with
.Xr OBJ_obj2txt 3 .
.It
Purposes the certificate is explicitly
.Em not
intended to be used for as set with
.Xr X509_add1_reject_object 3 ,
again each printed with
.Xr OBJ_obj2txt 3 .
.It
If
.Fa aux
contains data set with
.Xr X509_alias_set1 3 ,
the raw bytes are printed in unencoded form.
.It
If
.Fa aux
contains data set with
.Xr X509_keyid_set1 3 ,
the bytes are printed in hexadecimal notation with colons in between.
.El
.Pp
.Fn X509_print_ex_fp
is similar to
.Fn X509_print_ex
except that it prints to
.Fa fp .
.Pp
.Fn X509_print
and
.Fn X509_print_fp
are wrapper functions setting the
.Fa nameflags
to
.Dv XN_FLAG_COMPAT
and the
.Fa skipflags
to
.Dv X509_FLAG_COMPAT .
.Sh RETURN VALUES
.Fn X509_print_ex ,
.Fn X509_print_ex_fp ,
.Fn X509_print ,
and
.Fn X509_print_fp
return 1 if all requested information was successfully printed,
even if failures occurred while attempting to decode or print the
public key or X.509 version 3 extensions, or 0 if any other operation
failed.
.Pp
.Fn X509_CERT_AUX_print
always returns 1 and silently ignores write errors.
.Sh SEE ALSO
.Xr BIO_new 3 ,
.Xr X509_CERT_AUX_new 3 ,
.Xr X509_CRL_print 3 ,
.Xr X509_new 3 ,
.Xr X509_REQ_print_ex 3
.Sh HISTORY
.Fn X509_print
first appeared in SSLeay 0.5.1 and was changed to print to a
.Vt BIO
in SSLeay 0.6.0.
.Fn X509_print_fp
first appeared in SSLeay 0.6.0.
Both functions have been available since
.Ox 2.4 .
.Pp
.Fn X509_CERT_AUX_print
first appeared in OpenSSL 0.9.5 and has been available since
.Ox 2.7 .
.Pp
.Fn X509_print_ex
and
.Fn X509_print_ex_fp
first appeared in OpenSSL 0.9.7 and have been available since
.Ox 3.2 .
.Sh BUGS
If arbitrary data was stored into
.Fa x
using
.Xr X509_alias_set1 3 ,
these functions may print binary data and even NUL bytes.
